Network Support Library/RoseWare - Network Support Library.iso/btrieve/btr61m.exe/06CH3A.TXT

Text File | 1993-07-16 | 22KB | 643 lines

3       INSTALLING AND CONFIGURING BTRIEVE

This chapter describes how to install and configure
Btrieve.  It discusses the following topics:

o Installing Btrieve
o Configuring Btrieve
o Starting and Stopping Btrieve
o Rebuilding Existing Btrieve Files
o Using Btrieve with NetWare Runtime


Installing Btrieve

The following sections discuss the system requirements
and the installation procedure for Btrieve v6.1.


System Requirements

Make sure your system has the following:

o NetWare v3.11

  NOTE: Running Btrieve v6.1 in a NetWare v3.11 environment
  requires AFTER311.NLM, which Btrieve loads
  automatically.

o Adequate memory at the server to load the Btrieve NLM
  (approximately 528 KB) and the appropriate
  communications modules.

  NOTE: The memory required for the
  communications modules varies, depending on the
  values you specify for the Largest Record Size and
  Number of Remote Sessions configuration options.

o Adequate memory for the Btrieve Requester at each
  workstation.  Memory requirements vary, depending on
  the parameters you specify when you load the
  Requester.  These are the default parameters:

  o The DOS Requester requires approximately 29 KB.

  o The OS/2 Requester requires approximately 40 KB.

  o The Windows Requester requires approximately 30 KB.
    (To use the Windows Requester, you must also have
    the DOS Requester loaded.)

    NOTE: Btrieve also provides a requester for the
    UnixWare environment.  For information about this
    new UnixWare Requester, please refer to the Readme
    file that accompanies this release.


Using the NetWare INSTALL Utility

To install Btrieve, complete the following steps:

1.  Enter load install at the server console.

2.  In response to the Installation Options menu,
select Product Options to display the list of
currently installed products.

3.  Press the Insert key to copy Btrieve v6.x program
files to your server.  The system responds with the
following prompt:

Enter drive and/or path to new product source media

4.  In response to the prompt, specify the location of
the source media.

The default response, A; appears in the response
field.  Use the default if you are installing from the
distribution diskette.  If you are installing from
another source (for example, a NetWare volume and
path), enter the source volume and path at this time.
If the source media is not on the distribution
diskette, the source media you use must have the same
directory structure as that found on the distribution
diskette.

5.  When the Copy Btrieve Files to Fileserver menu
appears, select Copy Files.

6.  When the Existing Btrieve Program Files menu
appears, select either Overwrite or Rename.

o Overwrite - This option copies the Btrieve v6.x
  programs over the existing Btrieve programs.

  NOTE: The Overwrite option does not overwrite or rename
  existing Btrieve data files.

o Rename - This option renames your existing Btrieve
  programs so that you can run either the earlier
  version of Btrieve and Btrieve v6.x.  If you choose
  this option, the utility changes the first letter of
  the file extension for your existing Btrieve programs
  to $.  For example, program files that had the
  extension .NLM now have the extension .$LM, and
  program files with the extension .NCF now have the
  extension .$CF.

7.  When the Insert bstart Into...  menu appears,
select the appropriate option.

o SYS:\SYSTEM\STARTUP.NCF - This option places
  BSTART.NCF (the Btrieve batch file) into the
  network's STARTUP.NCF file.

o SYS:\SYSTEM\AUTOEXEC.NCF - This option places
  BSTART.NCF into your server's AUTOEXEC.NCF file.

o You Specify Drive, Path, and AUTOEXEC or STARTUP
  - This option lets you place BSTART.NCF into an
  AUTOEXEC.NCF or STARTUP.NCF file in a directory other
  than SYS:\SYSTEM.  For example, if you loaded NetWare
  from a network drive, you might specify that your
  AUTOEXEC.NCF file be loaded at L:\MYDIR\NW311.

o Exit - This option lets you choose to invoke
  BSTART.NCF manually.  If you choose this option, you
  exit the menu.  When installation is complete, the
  utility displays the following:  Program Files
  Successfully Copied to Fileserver

8.  To verify that the correct files are installed on
your server, press Esc to return to the Copy Btrieve
Files to Fileserver menu and select View Log of files
Copied.  A list of files copied (similar to the
following illustration) appears.  Compare this list to
the list of files in the release notes that accompany
the product shipment.

9.  After verifying the copied files, press Esc to
return to the Installation Options menu.

10.  Select Exit to go to the Currently Installed
Products menu.  Btrieve is listed as an option under
the Currently Installed Products menu.

11.  Highlight Btrieve and press Enter to invoke the
Btrieve Setup utility.  The Available Options menu
appears.  This menu provides the following options:

o Set Btrieve Configuration - Use this option to view
  or modify the current configuration options for
  Btrieve.

o Set Rebuild Configuration - Use this option to view
  or modify the current configuration options for the
  Rebuild utility.  ("Rebuilding Existing Btrieve
  Files"  discusses the Rebuild utility and
  its configuration options.)

  If you do not want to set
  configuration options or rebuild Btrieve files at
  this point, press Esc until you exit the INSTALL
  utility.

After loading Btrieve with the INSTALL utility, you
can configure Btrieve according to your Btrieve
application's requirements.  Use the guidelines
discussed in the next section, "Configuring Btrieve."
You can then activate Btrieve as discussed in "Starting
and Stopping Btrieve."


Configuring Btrieve

You can configure Btrieve by setting configuration
options.  When you load Btrieve with the INSTALL
utility, these options are set to their default
values.  (Table 3-1 shows the default values.)
However, your Btrieve application may require
different values for these options.

To determine which values your application requires,
refer to the documentation included with that
application.

Table 3-1 - Default Values for Configuration Options

Configuration Option            Default Value

Number of Open Files            20 files

Number of Handles            60 handles

Number of Locks             20 per client

Number of Transactions            15 transactions

Largest Compressed Record Size        0 KB

Largest Record Size            8,192 bytes

Largest Page Size            4,096 bytes

Number of Remote Sessions        15 sessions

Cache Allocation            256 KB

Perform Index Balancing         No

Logging of Selected Files        No

Create Btrieve Files in Pre v6.x Format No

Create Files as Transactional        No

Configure BSTART.NCF to Load BROUTER    No

The following section discusses each configuration
option individually.  You can change the values for
the configuration options by running the Btrieve Setup
utility (as described in "Running the Setup Utility").  The Setup
utility stores your changes in the BSTART.NCF NetWare
command file.


Configuration Options

This section lists the Btrieve configuration options
in the order in which they appear in the Setup
utility.  For each option, the discussion includes the
following:

o  Range of acceptable values
o  Default value
o  Approximate memory required
o  Description of the option


Number of Open Files
Range: 1 through 64,000 files
Default: 20 files
Approximate Memory Required: 425 bytes per file

This option specifies the maximum number of unique
Btrieve files that can be open at one time at the
server.  The value you specify determines the size of
the internal tables used to track active files.  Each
unique Btrieve file on the server counts as one file.


Number of Handles
Range: 1 through 64,000 file handles
Default: 60 handles
Approximate Memory Required: 200 bytes per handle

This option specifies the maximum number of file
handles that the Btrieve NLM can use at one time.
Keep in mind that the number of handles is different
from the number of open files.  That is, if two
sessions open the same file on the same server,
Btrieve counts it as one open file, but two different
file handles.  See "Number of Locks" (next) for a
definition of sessions.


Number of Locks
Range: 0 through 64,000 locks
Default: 20 locks per client session
Approximate Memory Required: 20 bytes per lock

This option sets the maximum number of records a
client session can lock at the server at one time.  (A
session occurs when a client uses the Btrieve
Requester or Message Router to communicate with the
Btrieve NLM, or when an NLM application calls Btrieve
directly.) This maximum applies to whichever type of
read lock (single record or multiple record) the
client session is using.  Single-record locks allow an
application to lock only one record at a time.
Multiple-record locks allow an application to lock more
than one record at a time.


Number of Transactions
Range: 0 through 64,000 transactions
Default: 15 transactions
Approximate Memory Required:  20 bytes + (2 * maximum
      number of files)

This option sets the maximum number of Btrieve clients
that can simultaneously have active transactions at
the server.  (Each of these clients can have only one
active transaction at the server.) For example, if you
specify 6 transactions, Btrieve creates a transaction
file at the server (BTRIEVE.TRN in the SYS:SYSTEM
directory) and allows a maximum of 6 clients to have
one active transaction each at the server.  If you
specify a value of 0, no clients can perform a Btrieve
transaction.


Largest Compressed Record Size
Range: 0 through 64 KB
Default: 0 KB
Approximate Memory Required:  2,048 bytes * specified
         value

This option allows you to allocate memory for a
compression buffer that Btrieve can use when you
access records in a Btrieve file created with the Data
Compression file attribute enabled.  Btrieve allocates
a compression buffer with a size of 2,048 bytes
multiplied by the value you specify for this option.
Use the following guidelines when specifying the value
for this option:

o If you use compressed Btrieve files, determine the
  size (in bytes) of the largest record in any of your
  compressed files.  Round the record size to the next
  whole kilobyte.  For example, if the largest record
  you need to access is 1,800 bytes, specify 2 for this
  option.  Btrieve will allocate 4,096 bytes (that is,
  2,048 * 2) of memory for the compression buffer.

o If every compressed file you use has Variable-tail
  Allocation Tables (VATs), set this option to the
  file's largest page size (in bytes) divided by 128.
  For example, if the largest page size is 1,024 bytes,
  specify 8 for this option.  Btrieve will allocate
  16,384 bytes (that is, 2,048 * 8) of memory for the
  compression buffer.

o If you do not use compressed files, set this value
  to 0.  You cannot improve performance, and may waste
  memory, by specifying a value higher than you need.


Largest Record Size
Range: 600 through 64,000 bytes
Default: 8,192 bytes
Approximate Memory Required: recordLength *
   (remoteSessions /5) + 1 +
   (remoteSessions * recordLength / 580) * 600

recordLength            538 + largest record size
remoteSessions          Number of remote sessions

This option specifies the length of the largest record
or record chunk that any remote Btrieve application
(excluding other NLMs that call Btrieve, such as
NetWare SQL) can access at the server.  A record chunk
is any arbitrary portion of a record, specified by its
offset and length.  Specify the length of the record
(or record chunk) in bytes.  Specifying a value higher
than you need does not improve performance and may
waste memory.

NOTE: For applications running on workstations, the maximum
record length is 57,000 for the DOS Requester, 65,000
for the OS/2 Requester, and 57,000 for the Windows
Requester.


Largest Page Size
Range: 512 through 4,096 bytes
Default: 4,096 bytes
Approximate Memory Required: Not applicable

This option specifies the maximum page size (in bytes)
of any Btrieve file you want to access.  The page size
must be a multiple of 512 bytes, but no greater than
4,096 bytes.  Setting the page size to 512, 1,024,
2,048, or 4,096 can improve performance because these
page sizes correspond to disk block sizes.  If you set
the page size to 1,536, 2,560, 3,072, or 3,584, a
given disk read may span two disk blocks and therefore
require two disk accesses per page.


Number of Remote Sessions
Range: 1 through 64,000 sessions
Default: 15 sessions
Approximate Memory Required:  150 bytes * number of
remote sessions

This option specifies the maximum number of SPX
sessions that can access the remote Btrieve NLM at one
time.  (A session occurs when a client uses the
Btrieve Requester or the Message Router to communicate
with the remote Btrieve NLM.) Each session is allocated
two packet buffers for Btrieve requests.

NOTE: If you
receive a Status Code 96, increase the value for this
option.  However, do not specify a value higher than
you need.  Specifying a value that is too high does
not improve performance; instead, it uses memory that
NetWare or other processes might need.


Cache Allocation
Range: 32 through 64,000 KB
Default: 256 KB
Approximate Memory Required: Not applicable

This option specifies the size of the cache (in
kilobytes) that Btrieve allocates.  To achieve best
performance, allocate a cache size equal to the sum of
the sizes of the files you are using.  However, be
careful not to take all available cache, especially if
the server is running other applications.  You cannot
improve performance, and may waste memory, by
specifying a value higher than you need.


Perform Index Balancing
Range: Yes or No
Default: No
Approximate Memory Required:  Not applicable

When an index page becomes full, Btrieve automatically
creates a new index page and splits the values in the
full index page between the two index pages.  The
Perform Index Balancing option lets you avoid creating
a new index page every time an old one fills up.

If you specify Yes for this option, Btrieve looks for
available space in sibling index pages each time an
index page becomes full.  Btrieve then rotates values
from the full index page into the pages that have
space available.  Index balancing increases index page
utilization, results in fewer index pages, and
produces an even distribution of keys among nodes on
the same level, thus increasing performance during Get
operations.  However, when you specify Yes for this
option, Btrieve requires extra time to examine more
index pages and may require more disk I/O during
Insert, Update, and Delete operations.

NOTE: You can also specify index balancing on a file-by-file
basis by setting a bit in the file flag╒s word when
the file is created.  If you specify Yes to the
Perform Index Balancing option, Btrieve performs index
balancing on every file regardless of the balanced
file flag specification.


Logging of Selected Files
Range: Yes or No
Default: No
Approximate Memory Required: Not applicable

This option controls whether Btrieve logs operations
executed on selected files.  If you specify Yes,
Btrieve logs all operations that change any file
listed in the BLOG.CFG file on Btrieve╒s server
volume.  If you specify No, Btrieve performs no
logging.  For more information on logging and the Roll
Forward utility, see Chapter 5, "Using Btrieve
Utilities."


Create Btrieve Files in Pre v6.x Format
Range: Yes or No
Default: No
Approximate Memory Required: Not applicable

This option specifies that all files be created in a
Btrieve version prior to v6.x.  Use this option only
if you need backward compatibility with a previous
version of Btrieve.  For example, if you want to
create files with Btrieve v6.x and you want to use
those files with Btrieve v5.x, specify Yes for this
option.

NOTE: Btrieve v6.x can read files that previous
versions of Btrieve created.  In addition, it can
write to files using the existing file format.  In
other words, it writes to v5.x files using the v5.x
format and writes to v6.x files using the v6.x format.


Create Files as Transactional
Range: Yes or No
Default: No
Approximate Memory Required: Not applicable

This option controls whether Btrieve automatically
flags each file as transactional when you create it.
The transactional flag indicates that the NetWare
Transaction Tracking System (TTS) is protecting the
file.  TTS ensures that, when a file is being
modified, either all changes are made or no changes
are made, thus preventing data damage.


Configure BSTART.NCF to Load BROUTER
Range: Yes or No
Default: No
Approximate Memory Required: Not applicable

This option controls whether the Message Router is
loaded during the execution of the BSTART.NCF NetWare
command file.  The Message Router allows other NLMs
(such as NetWare SQL) to communicate with remote
servers on which Btrieve is loaded.  If you want to
access Btrieve data on a remote server, specify Yes
for this option.


Running the Setup Utility

Use the Setup utility to set the Btrieve configuration
options interactively.  The utility automatically
checks to see if the values you enter are within the
correct ranges.  You can run the Setup utility either
at the server console or at a workstation running the
NetWare Remote Console utility (RCONSOLE).

To run the Setup utility, complete the following steps.

NOTE: To get help with the Setup utility, press F1.  The
help information is context sensitive, relevant to
your location in the program.  To exit the utility,
press the Esc key.

1.  Enter load bsetup at the prompt to start the
utility.  If your SYS:SYSTEM directory does not
contain the BSTART.NCF command file, the Setup utility
displays a window asking if you want to create it.  If
that window appears on your screen, create the
BSTART.NCF file at this time.

The Available Options menu appears.

This menu provides the following options:

o Set Btrieve Configuration - Use this option to view
  or modify the current configuration options for
  Btrieve.

o Set Rebuild Configuration - Use this option to run
  the Rebuild utility, view or modify the current
  Rebuild configuration options, and view the Rebuild
  log file.  ("Rebuilding Existing Btrieve Files"
  discusses the Rebuild utility and its configuration
  options.)

2.  To change configuration options, select Set
Btrieve Configuration.

3.  When the Current Btrieve Configuration screen
appears, use the Up- and Down-Arrow keys to highlight
the configuration option you want to change, and press
the Enter key.  A flashing cursor appears.

4.  Use the Backspace key to remove the old value;
then, type the new value and press the Enter key.

If you enter an invalid value for an option, the utility
displays a message indicating the valid values.

NOTE: To see the valid values for any option, move the cursor
to that option, press the Enter key, and then press
the F1 key.  You can also refer to "Configuration
Options" for more information about these
options and their values.

5.  Repeat Steps 3 and 4 until you have changed all
the options you want to modify.

6.  When you are ready to exit the Current Btrieve
Configuration screen, press the Esc key.

7.  When the Save Configuration Changes?  screen
appears, select Yes to save your changes or No to
abandon the changes.

If you select Yes, the Setup utility writes the
configuration values you specified to the BSTART.NCF
file.

IMPORTANT: Do not edit the BSTART.NCF command file for
Btrieve.  Always use the Setup utility to make any
modifications to the configuration values in the
BSTART.NCF file.

Before your configuration changes can take effect, you
must unload the existing Btrieve NLM, BSPXCOM, and the
Message Router (using the BSTOP command), and then
reload them by entering the BSTART command.

BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB.  To unload these
modules, type UNLOAD followed by the module name.

8.  To exit the Setup utility, press the Esc key until
the Exit window appears, and then select Yes.
Starting and Stopping Btrieve

This section discusses starting and stopping Btrieve.
Before starting Btrieve v6.x, you must first check for
any extraneous pre-image files (files with a .PRE
extension) and then unload the earlier version of
Btrieve.

NOTE: If you need to preserve your Btrieve v5.x files, you
can use Btrieve v6.x to read them.


Checking for Extraneous Pre-Image Files

If you have any extraneous .PRE files in your
database, you must remove them before starting Btrieve
v6.x.  The following procedure explains how to check
for and remove extraneous .PRE files.

IMPORTANT:  You must have
Btrieve v5.x or v6.0 loaded before performing these
steps.

1.  Using your existing version of Btrieve (such as
v5.x or v6.0), open the Btrieve data file
corresponding to the .PRE file in Exclusive mode.

2.  Perform a Get First operation.

3.  Perform an Update operation (this will not change
the record).

4.  Close the Btrieve data file (this should cause
Btrieve to delete the .PRE file).

5.  Any .PRE files that remain for the designated file
after you perform Steps 1 through 4 are extraneous.
Delete them at this time.

6.  Repeat Steps 1 through 5 to find and delete any
other extraneous .PRE files.

IMPORTANT: If you do not remove the extraneous .PRE files before
starting Btrieve v6.x, file corruption may occur.